home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 1.iso / toolbox / documents / OpenGL / extensions / spec / visual_info.spec < prev    next >
Encoding:
Text File  |  1996-11-11  |  11.3 KB  |  298 lines
  1. Name
  2.  
  3.     EXT_visual_info
  4.  
  5. Name Strings
  6.  
  7.     GL_EXT_visual_info
  8.     GLX_EXT_visual_info
  9.  
  10. Version
  11.  
  12.     $Date: 1995/09/30 02:33:47 $ $Revision: 1.1 $
  13.  
  14. Number
  15.  
  16.     28
  17.  
  18. Dependencies
  19.  
  20.     SGIS_multisample affects the definition of this extension
  21.  
  22. Overview
  23.  
  24.     The current GLX specification requires that RGBA extended visuals be
  25.     associated only with X visual types TrueColor and DirectColor.  This
  26.     extension defines the semantics of associating a GLX RGBA visual with
  27.     four other X visual types: PseudoColor, StaticColor, GrayScale, and
  28.     StaticGray.  In each of these cases, the red component is used to
  29.     generate the display, and the green and blue components, if present,
  30.     are ignored for display purposes.  Provision is made for a GLX
  31.     application to determine which X visual type is associated with a
  32.     GLX visual, and to specify which X visual type is desired, when using
  33.     glXChooseVisual.
  34.  
  35.     The OpenGL RGBA rendering semantics are more powerful than the OpenGL
  36.     index rendering semantics.  By extending the number of X visual types
  37.     that can be associated with an RGBA color buffer, this extension allows
  38.     RGBA rendering semantics to be used with color index and gray scale
  39.     displays.  An especially useful application of this extension is
  40.     support of one- and two-component RGBA visuals; visuals whose green,
  41.     blue, and sometimes alpha components have no bitplanes.
  42.  
  43.     This extension also allows GLX index visuals to be associated with
  44.     X visual types GrayScale and StaticGray.
  45.  
  46.     In addition, this extension also provides a means to request a visual
  47.     with a transparent pixel and to query whether a visual supports a
  48.     transparent pixel value and the value of the transparent pixel.
  49.     Note that the notion of level and transparent pixels are orthogonal as
  50.     both layer 1 and layer 0 visuals may or may not have a transparent pixel
  51.     value.
  52.  
  53. New Procedures and Functions
  54.  
  55.     None
  56.  
  57. New Tokens
  58.  
  59.     Accepted by the <attrib> parameter of glXGetConfig, and by the
  60.     <attrib_list> parameter of glXChooseVisual:
  61.  
  62.     GLX_X_VISUAL_TYPE_EXT        0x22
  63.     GLX_TRANSPARENT_PIXEL_EXT    0x23
  64.     GLX_TRANSPARENT_COLOR_EXT    0x24
  65.     GLX_TRANSPARENT_INDEX_EXT    0x25
  66.  
  67.  
  68.     Returned by glXGetConfig, and accepted by the <attrib_list>
  69.     parameter of glXChooseVisual (following the GLX_X_VISUAL_TYPE_EXT
  70.     token):
  71.  
  72.     GLX_TRUE_COLOR_EXT        0x1
  73.     GLX_DIRECT_COLOR_EXT        0x2
  74.     GLX_PSEUDO_COLOR_EXT        0x3
  75.     GLX_STATIC_COLOR_EXT        0x4
  76.     GLX_GRAY_SCALE_EXT        0x5
  77.     GLX_STATIC_GRAY_EXT        0x6
  78.  
  79. Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation)
  80.  
  81.     None
  82.  
  83. Additions to Chapter 3 of the 1.0 Specification (Rasterization)
  84.  
  85.     None
  86.  
  87. Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations and
  88. the Framebuffer)
  89.  
  90.     In section 4.1.6 (Blending) follow the sentence "If a color buffer has
  91.     no A value, then it is as if the destination A value is 1." with the
  92.     sentence "If the color buffer has no R, G, or B value, then it is as
  93.     if the destination R, G, or B value is 0."
  94.  
  95.     In section 4.3.2 (Reading Pixels) follow the sentence "If the framebuffer
  96.     does not support alpha values then the A that is obtained is 1.0." with
  97.     the sentence "If the framebuffer does not support red, green, or blue
  98.     values, then the R, G or B that is obtained is 0.0."
  99.  
  100. Additions to Chapter 5 of the 1.0 Specification (Special Functions)
  101.  
  102.     None
  103.  
  104. Additions to Chapter 6 of the 1.0 Specification (State and State Requests)
  105.  
  106.     None
  107.  
  108. Additions to the GLX Specification
  109.  
  110.     The X visual type of a GLX visual can be queried using glXGetConfig().
  111.  
  112.     Attribute          Type        Notes
  113.     ---------          ----        -----
  114.     GLX_USE_GL          boolean   True if OpenGL rendering is supported
  115.     GLX_BUFFER_SIZE          integer   depth of the color buffer
  116.     GLX_LEVEL          integer   frame buffer level
  117.     GLX_RGBA          boolean   True if in RGBA mode, False if color index
  118.     GLX_DOUBLEBUFFER      boolean   True if color buffers have front/back pairs
  119.     GLX_STEREO          boolean   True if color buffers have left/right pairs
  120.     GLX_AUX_BUFFERS          integer   number of auxiliary color buffers
  121.     GLX_RED_SIZE          integer   number of bits of Red if in RGB mode
  122.     GLX_GREEN_SIZE          integer   number of bits of Green if in RGB mode
  123.     GLX_BLUE_SIZE          integer   number of bits of Blue if in RGB mode
  124.     GLX_ALPHA_SIZE          integer   number of bits of Alpha if in RGB mode
  125.     GLX_DEPTH_SIZE          integer   number of bits in the depth buffer
  126.     GLX_STENCIL_SIZE      integer   number of bits in the stencil buffer
  127.     GLX_ACCUM_RED_SIZE      integer   number of bits of Red in the accumulation buffer
  128.     GLX_ACCUM_GREEN_SIZE      integer   number of bits of Green in the accumulation buffer
  129.     GLX_ACCUM_BLUE_SIZE      integer   number of bits of Blue in the accumulation buffer
  130.     GLX_ACCUM_ALPHA_SIZE      integer   number of bits of Alpha in the accumulation buffer
  131.     GLX_SAMPLE_BUFFERS_SGIS      integer   number of multisample buffers
  132.     GLX_SAMPLES_SGIS      integer   number of samples stored in each multisample buffer
  133.     GLX_X_VISUAL_TYPE_EXT      integer   X visual type of the GLX visual
  134.     GLX_TRANSPARENT_PIXEL_EXT boolean   True if the visual contains a transparent pixel
  135.     GLX_TRANSPARENT_INDEX_EXT integer   transparent index value.
  136.     GLX_TRANSPARENT_COLOR_EXT color*4   transparent color value (RGBA).
  137.  
  138.     type color is essentially the OpenGL signed integer color type which
  139.     maps to an OpenGL float color in the range (0.0,1.0) as described
  140.     in table 2.4 of the 1.0 OpenGL specification.
  141.  
  142.     Table 1: Configuration attributes
  143.  
  144.     glXGetConfig returns one of the values in table 2 (below) when called
  145.     with attribute name GLX_X_VISUAL_TYPE_EXT.
  146.  
  147.     GLX token name            X Visual Type
  148.     --------------            -------------
  149.     GLX_TRUE_COLOR_EXT        TrueColor
  150.     GLX_DIRECT_COLOR_EXT        DirectColor
  151.     GLX_PSEUDO_COLOR_EXT        PseudoColor
  152.     GLX_STATIC_COLOR_EXT        StaticColor
  153.     GLX_GRAY_SCALE_EXT        GrayScale
  154.     GLX_STATIC_GRAY_EXT        StaticGray
  155.  
  156.     Table 2: X visual type token values
  157.  
  158.     Replace the GLX specification discussion of glXChooseVisual with
  159.     the following text:
  160.  
  161.     glXChooseVisual is used to find a visual that matches the client's
  162.     specified attributes.
  163.  
  164.     XVisualInfo* glXChooseVisual( Display *dpy, int screen,
  165.                       int *attrib_list );
  166.  
  167.     glXChooseVisual returns a pointer to an XVisualInfo structure
  168.     describing the visual that best meets a minimum specification.  The
  169.     boolean GLX attributes of the visual that is returned will match the
  170.     specification exactly.  The integer GLX attributes will meet or exceed
  171.     the specified minimum values.  The enumerated GLX attributes are
  172.     matched in an attribute-specific manner.  If no conforming visual
  173.     exists, NULL is returned.
  174.  
  175.     If GLX_RGBA is in <attrib_list> then the resulting visual will be of type
  176.     RGBA, meaning that it has up to four color components, and that OpenGL
  177.     renders to it using its RGBA semantics.  RGBA visuals may have any
  178.     of the six X Visual types: TrueColor, DirectColor, PseudoColor,
  179.     StaticColor, GrayScale, and StaticGray.  The enumerated attribute
  180.     GLX_X_VISUAL_TYPE_EXT specifies which X visual type is required
  181.     for the requested GLX visual.  In attrib_list it is followed by one
  182.     of six possible values, indicating which X visual type is required.
  183.  
  184.     GLX token name            X Visual Type
  185.     --------------            -------------
  186.     GLX_TRUE_COLOR_EXT        TrueColor
  187.     GLX_DIRECT_COLOR_EXT        DirectColor
  188.     GLX_PSEUDO_COLOR_EXT        PseudoColor
  189.     GLX_STATIC_COLOR_EXT        StaticColor
  190.     GLX_GRAY_SCALE_EXT        GrayScale
  191.     GLX_STATIC_GRAY_EXT        StaticGray
  192.  
  193.     If GLX_X_VISUAL_TYPE_EXT is not included in <attrib_list>, only
  194.     visuals with X visual type TrueColor and DirectColor are considered
  195.     for return.  If all other attributes are equivalent, then a
  196.     TrueColor visual will be chosen in preference to a DirectColor
  197.     visual.  X visual types PseudoColor, StaticColor, GrayScale, and
  198.     StaticGray generate their display values using only the red
  199.     component of the framebuffer.  X visual types TrueColor and
  200.     DirectColor generate their red, green, and blue display values from
  201.     the red, green, and blue framebuffer components.
  202.  
  203.     If GLX_RGBA is not in <attrib_list> then the resulting visual will be
  204.     of type index, meaning that it has only a single index value, and that
  205.     OpenGL renders to it using its color index semantics.  The enumerated
  206.     attribute GLX_X_VISUAL_TYPE_EXT specifies which X visual type is
  207.     required for the requested GLX visual.  In <attrib_list> it is
  208.     followed by one of four possible values, indicating which X visual
  209.     type is required.
  210.  
  211.     GLX token name            X Visual Type
  212.     --------------            -------------
  213.     GLX_PSEUDO_COLOR_EXT        PseudoColor
  214.     GLX_STATIC_COLOR_EXT        StaticColor
  215.     GLX_GRAY_SCALE_EXT        GrayScale
  216.     GLX_STATIC_GRAY_EXT        StaticGray
  217.  
  218.     If GLX_X_VISUAL_TYPE_EXT is not included in <attrib_list>, only
  219.     visuals with X visual type PseudoColor and StaticColor are considered
  220.     for return.  If all other attributes are equivalent, then a
  221.     PseudoColor visual will be chosen in preference to a StaticColor
  222.     visual.
  223.  
  224.     All boolean GLX attributes default to False except GLX_USE_GL, which
  225.     defaults to True.  All integer attributes default to zero.
  226.  
  227.     Default specifications are superseded by the attributes included in
  228.     <attrib_list>.  Integer attributes are immediately followed by the
  229.     corresponding desired value.  Boolean attributes appearing in
  230.     <attrib_list> have an implicit True value; such attributes are never
  231.     followed by an explicit True or False value.  The list is terminated
  232.     with None.
  233.  
  234.     To free the data returned, use XFree().
  235.  
  236.     NULL is returned if an undefined GLX attribute is encountered, or
  237.     if an unacceptable enumerated attribute value is encountered.
  238.  
  239. GLX Protocol
  240.  
  241.     Six new property type/property value pairs are included in the property 
  242.     list of each visual returned by glXGetVisualConfigs. The property type/property 
  243.     value pairs are encoded as
  244.  
  245.     4           ENUM                    property type
  246.          0x22            GLX_X_VISUAL_TYPE_EXT        
  247.     4           ENUM                    property value
  248.         0x1            GLX_TRUE_COLOR_EXT    
  249.         0x2            GLX_DIRECT_COLOR_EXT
  250.         0x3            GLX_PSEUDO_COLOR_EXT
  251.         0x4            GLX_STATIC_COLOR_EXT    
  252.         0x5            GLX_GRAY_SCALE_EXT
  253.         0x6            GLX_STATIC_GRAY_EXT
  254.  
  255.     4            ENUM            property type
  256.                 0x23                    GLX_TRANSPARENT_PIXEL_EXT
  257.     4           BOOL32                  property value
  258.  
  259.     4           ENUM                    property type
  260.                 0x24                    GLX_TRANSPARENT_INDEX_EXT
  261.     4           BOOL32                  property value
  262.  
  263.     4           ENUM                    property type
  264.                 0x25                    GLX_TRANSPARENT_RED_VALUE
  265.     4           INT32                   property value
  266.  
  267.     4           ENUM                    property type
  268.                 0x26                    GLX_TRANSPARENT_GREEN_VALUE
  269.     4           INT32                   property value
  270.  
  271.     4           ENUM                    property type
  272.                 0x27                    GLX_TRANSPARENT_BLUE_VALUE
  273.     4           INT32                   property value
  274.  
  275.  
  276. Dependencies on SGIS_multisample
  277.  
  278.     If SGIS_multisample is not supported, references to
  279.     GLX_SAMPLE_BUFFERS_SGIS and GLX_SAMPLES_SGIS in this document are
  280.     invalid and should be ignored.
  281.  
  282. Errors
  283.  
  284.     None
  285.  
  286. New State
  287.  
  288.     None
  289.  
  290. New Implementation Dependent State
  291.  
  292.     Get Value          Get Command    Type
  293.     ---------          -----------    ----
  294.     GLX_X_VISUAL_TYPE      glXGetConfig    Z6
  295.     GLX_TRANSPARENT_PIXEL glXGetConfig
  296.     GLX_TRANSPARENT_INDEX glXGetConfig
  297.     GLX_TRANSPARENT_COLOR glXGetConfig
  298.